This vignette demonstrates how to construct a simple NG-CHM, export it to a file, and embed it into RMarkdown.

The required packages can be installed with:

install.packages("NGCHM")
install.packages("NGCHMDemoData", repos = c("https://md-anderson-bioinformatics.r-universe.dev", "https://cloud.r-project.org"))
install.packages("NGCHMSupportFiles", repos = c("https://md-anderson-bioinformatics.r-universe.dev", "https://cloud.r-project.org"))
install.packages("htmltools") # used to embed the NG-CHM into RMarkdown

R Code Example

The following R code demonstrates how to create a NG-CHM from the TCGA breast cancer data, export it to a file, and embed it into an Rmarkdown document. For use by the NGCHM package, the data must be formatted such that:

  • The heat map data is a matrix with rownames and colnames
  • The covariate data is a named vector.
    • For a row/column covariate, at least one name must be in the row/colnames of the heat map matrix data.
matrix_data_file <- system.file("extdata", "TCGA.BRCA.Expression.csv", package = "NGCHMDemoData")
matrix_data <- as.matrix(read.csv(matrix_data_file, header = TRUE, row.names = 1, check.names = FALSE))
covariate_data_file <- system.file("extdata", "TCGA.BRCA.TP53Mutation.csv", package = "NGCHMDemoData")
covariate_data <- as.matrix(read.csv(covariate_data_file, row.names = 1))
covariate_vector <- as.vector(covariate_data) # create vector of mutation data
names(covariate_vector) <- rownames(covariate_data) # set the names
library(NGCHM)
hm <- chmNew("TCGA BRCA Expression", matrix_data)
covariateBar <- chmNewCovariate("TP53 Mutation", covariate_vector)
hm <- chmAddCovariateBar(hm, "column", covariateBar)
library(NGCHMSupportFiles) # required for chmExportToHTML and chmExportToFile
chmExportToHTML(hm, "tcga-brca.html", overwrite = TRUE)
chmExportToFile(hm, "tcga-brca.ngchm", overwrite = TRUE)
library("htmltools")
filePath <- paste(getwd(), "/tcga-brca.html", sep = "")
htmltools::tags$iframe(src = filePath, width = "100%", height = 700)

Explanation of R Code Example

NGCHMDemoData Package

This vignette uses an additional package of demo data, NGCHMDemoData, which can be installed from our R-Universe repository.

The sample data includes a matrix of gene expression data containing 3437 genes (rows) and 200 samples (columns) of breast cancer data from The Cancer Genome Atlas (TCGA).

TCGA.BRCA.Expression.csv snippet
TCGA-AO-A0JJ-01A TCGA-E9-A1R4-01A TCGA-E9-A6HE-01A TCGA-E2-A1L9-01A
TSPAN6 11.838 9.483 11.157 11.536
CFH 12.033 10.835 10.824 12.878
ENPP4 11.372 10.749 9.721 11.008
SEMA3F 12.722 12.393 13.338 12.451

IMPORTANT: In order to be used as the basis for an NG-CHM, a matrix should have both rownames and colnames.

The sample data also includes a vector of TP35 mutation status for the TCGA samples in the matrix. This data will be used to construct a covariate bar.

TCGA.BRCA.TP53Mutation.csv snippet
MutationState
TCGA-AO-A0JJ-01A WT
TCGA-E9-A1R4-01A WT
TCGA-E9-A6HE-01A WT
TCGA-E2-A1L9-01A WT
TCGA-E9-A245-01A WT
TCGA-AO-A0JG-01A WT
TCGA-C8-A1HE-01A WT
TCGA-C8-A12W-01A MUT

IMPORTANT: In order to be used as the basis for a row/column covariate bar, the data should be formatted as a named vector with at least one name in common with the col/rownames of the matrix.

The NGCHMDemoData package includes these datasets as .csv file. The expression data should be formatted as a matrix with row and column names. The covariate data should be formatted as a named vector. Because this covariate data is a column covariate, the names of the vector match the colnames of the matrix.

library(NGCHMDemoData)
# Read in the expression data, and convert to a matrix
matrix_data_file <- system.file("extdata", "TCGA.BRCA.Expression.csv", package = "NGCHMDemoData")
matrix_data <- as.matrix(read.csv(matrix_data_file, header = TRUE, row.names = 1, check.names = FALSE))
# Read in the mutation data, and format as a named vector
covariate_data_file <- system.file("extdata", "TCGA.BRCA.TP53Mutation.csv", package = "NGCHMDemoData")
covariate_data <- as.matrix(read.csv(covariate_data_file, row.names = 1))
covariate_vector <- as.vector(covariate_data) # create vector of mutation data
names(covariate_vector) <- rownames(covariate_data) # set the names

Creating a NG-CHM

The chmNew() function creates the NG-CHM object. The first argument is the name of the NG-CHM, and the second argument is the matrix data.

library(NGCHM)
hm <- chmNew("TCGA BRCA Expression", matrix_data)

A covariate bar can be created with chmNewCovariate(). The first argument is the name of the covariate, and the second argument is the named vector of covariate data. The chmAddCovariateBar() function adds the covariate bar to the NG-CHM. The first argument is the NG-CHM, the second argument is the type of covariate bar (‘column’ or ‘row’), and the third argument is the covariate bar object.

covariateBar <- chmNewCovariate("TP53 Mutation", covariate_vector)
hm <- chmAddCovariateBar(hm, "column", covariateBar)

Export to File

The NG-CHM can be exported to two different file types:

  1. An HTML file that can be emailed to collaborators, opened in a web browser, or embedded in an RMarkdown file.
  2. A ‘.ngchm’ file that can be opened in the [NGCHM Viewer]https://www.ngchm.net/Downloads/ngChmApp.html).

Both methods use files from the NGCHMSupportFiles package. When loaded, NGCHMSupportFiles sets environment variables pointing to these additional files.

library(NGCHMSupportFiles)
#> Environment variable SHAIDYMAPGEN set to /Users/runner/work/_temp/Library/NGCHMSupportFiles/java/ShaidyMapGen.jar
#> Environment variable NGCHMWIDGETPATH set to /Users/runner/work/_temp/Library/NGCHMSupportFiles/js/ngchmWidget-min.js

1. Export to HTML

The NG-CHM can be exported as an HTML file with the chmExportToHTML() function. The first argument is the NG-CHM created above. The second argument is the desired filename. Here we also use overwrite=TRUE to overwrite the file if it already exists.

chmExportToHTML(hm, "tcga-brca.html", overwrite = TRUE)

The file ‘tcga-brca.html’ can be shared with collaborators and opened in a web browser.

2. Export to .ngchm File

Alternatively, .ngchm file can be created with the chmExportToFile() function.

chmExportToFile(hm, "tcga-brca.ngchm", overwrite = TRUE)

The file ‘tcga-brca.ngchm’ can be opened in the NG-CHM Viewer. IMPORTANT: The filename must end with ‘.ngchm’ to open in the NG-CHM Viewer.

Embed into RMarkdown

The .html file can be embedded into RMarkdown via htmltools::includeHTML():

library('htmltools')
filePath = paste(getwd(),'/tcga-brca.html',sep='')
htmltools::includeHTML(filePath)
#> Warning: `includeHTML()` was provided a `path` that appears to be a complete HTML document.
#>  Path: /Users/runner/work/NGCHM-R/NGCHM-R/vignettes/tcga-brca.html
#>  Use `tags$iframe()` to include an HTML document. You can either ensure `path` is accessible in your app or document (see e.g. `shiny::addResourcePath()`) and pass the relative path to the `src` argument. Or you can read the contents of `path` and pass the contents to `srcdoc`.